Software Vault: The Games Collection 1/software vault.zip/software vault/CDR10/COMP91A.ZIP/COMPILER.TXT

Text File | 1993-06-04 | 18KB | 390 lines

Universal Hint System
Revision 91a
Compiler for MS-DOS, Version 1.50
  (June 3, 1993)

Copyright 1992-1993 by Jason Strautman


I assume that anyone who is about to write a file already has downloaded
and used a 91a UHS reader, either for DOS or Windows.  If you have not
already done so, make sure that you do before writing any file, so that you
can get an idea as to what the file should be like.  You should also read a
copy of the hint writing guidelines included in this ZIP archive for some
helpful hints.


Hunk Types
==========

A 91a UHS file is composed of a series of various types of hunks.  A hunk
may either hold information, such as hints or author credits, or other
hunks.  Each hunk will contain a title which is shown in the readers for
selection by the user.  The hunk name may be abbreviated to 4 characters.
Here are the types of hunks:


[subject]
---------
This may be the most important of the hunks in the UHS file, since it is
used to group all of the other hunks, including other [subject] hunks.  You
will probably want to use several levels of [subject]s in the file, to help
organize your file.

There is no extra data in the [subject]; only a title and nested hints are
used.


[hint]
------
A hint may contain an unlimited number of ten-line clues.  The title should
pose either a problem ("I can't get through the door!") or a question ("How
do I get through the door?").  The data that follows are the hints that
answer the problem/question in the title.  Each new hint should begin with
the string ">> ", including the space.  The hint should follow on the same
line.  If you need to use several lines in the hint, leave out that
identifier, and only include the hint line in the data.


[comment] and [credit]
----------------------
Both of these include a title and up to ten lines of data.  [credit]s
contain information about the author(s) of the file, while [comment]s cover
anything else, except for game hints.  [comment]s are often used to explain
the file, such as how it is structured.  See the guidelines for more
information.


[GIFa]
------
UHS 91a files may contain embedded GIF graphics, with a maximum resolution
of 320x200, and no more than 16 colors.  These graphics may be used to draw
maps or point out an area on a screen shot.  The data in the outline should
be one line that has the path and filename of the GIF file.  The proper data
will be inserted into the compiled file.


Additional hunks will be added by the compiler.  However, you do not need to
worry about writing these hunks yourself.


The Outline
===========

In order to create a compiled file, you will need to create an outline that
gives the data which will be placed in the hunks.  The first level of the
outline is a single [subject] hunk, whose title is also the title of the
game for which you are writing hints.  This [subject] is automatically
selected when the file is loaded.

Every hunk after the [subject] should be indented two spaces.  Indention
tells the compiler that the hunks that follow are embedded in the previous
[subject].  You should also indent an additional two spaces as more levels
of hunks are used.  All hunks that are on the same level will be indented
the same amount of space.  You should "un-indent" to separate hunks on the
same level into different menus.  Here is an example.  (Any text in curly
brackets is an added comment, that should not be included in the outline
that you write.)

[subject] Sample File  {Notice that the title goes on the same line,}
                       {with a space separating the two.}
  [subject] Grouping 1 (Item 1)
    [hint] Menu 1; Item 1
    [hint] Menu 1; Item 2
    [hint] Menu 1; Item 3
  [subject] Grouping 2 (Item 2)  {The indentation has changed.  This means}
                                 {that the a new menu has been started.}
    [hint] Menu 2; Item 1
    [hint] Menu 2; Item 2
    [hint] Menu 2; Item 3
    [subject] Grouping 3 (Item 4 on Menu 2)
      [comment] Menu 3; Item 1
      [hint] Menu 3; Item 2
      [hint] Menu 3; Item 3
  [subject] Grouping 4 (Item 3)  {This is on the same level as groupings 1}
                                 {and 2, since is indented the same amount.}

The top menu of the file contains three choices: "Grouping 1", "Grouping 2",
and "Grouping 3".  If the user selects "Grouping 1", then three choices will
be presented.  "Grouping 2" is outdented from the three hints above it, so
the compiler knows that item 3 is the last one on the first menu.  But since
this grouping is aligned with the first one (and nothing is outdented
between the two groupings), both are found on the same menu.  The second
grouping has four items, including one additional grouping.  Notice that all
are on the same level of indentation.  But "Grouping 3" provides even
further structuring on the file, which contains three additional choices.
"Grouping 4" is to the left of both "Grouping 3" and "Menu 3; Item 3".  Both
groupings 2 and 3 are ended, since this [subject] is outdented from the
items under the previous two subject.  But once again, the [subject] is on
the same level as the first two, so all are on the same menu.

The data of a hunk is also indented two spaces from its title line.  But
with the exception of the [subject] hunk, no additional hunks may be added
inside another.  A [comment] hunk would be written as follows:

[comment] Things to Know
  This is a properly written file, or at least a portion of one.  In a real
  file, there would be a [subject] above this, and this hunk would be
  indented, since it is a part of that main [subject].
  [hint] But this hunk is illegal.
    >> It should be on the same level as the *title* of the [comment], as
    found in the next [hint].
[hint] Now this is correct.
  >> Notice how the title is aligned with the title of the [comment], since
  both should be on the same level of the file.
  >> If you didn't want these two hunks to appear on the same menu, you
  would have to use a [subject] to separate them.

In your outline, you may use blank lines for clarity.  You can also use
semicolons (";") to mark comments that will not be included in the compiled
file.  The semicolons should be in the first column of the line, not
indented.

Also note that the 78-character limit mentioned in the guidelines does not
include any indentation, the type of hunk included in square brackets, or
the ">> " of a new line of hints.  Begin your count with the first character
of the title or data.


Sample Outline
==============

This is a short version of how a UHS outline should be written, and of how
the file might be structured.  I have used the four-character abbreviations
for the hunk names.  And in case you are printing this text file out, I have
cut off lines longer than 80 characters, even though you can use longer
lines in the outlines.  Just make sure that the data is shorter than 78
characters.

[subj] UHS 91a Sample File

; The following block is the first selection on the "main menu"
  [subj] General Information
    [comm] Everything you wanted to know about the UHS, but were afraid to ask:
      The Universal Hint System was invented by Jason Strautman (CIS [72337,261
      AOL JStrautman).
    [cred] About the file author.
      Jason (we've seen his name a lot on this file, haven't we?) Strautman
      wrote this file.  He can be reached on CompuServe at [72337,2611], or
      on AOL as JStrautman.
    [cred] About SAMPLE's publisher.
      If SAMPLE were a real game, then you might see the game's publisher,
      designer, programmers, or other related people mentioned here.  But since
      SAMPLE doesn't exist, then you won't see anything here.
    [comm] Writing your own UHS file
      I'm not going to go through that long speech, since it's in this manual.

; Second selection
  [subj] The Mountains
    [hint] How do I get past the small giant?
      >> First of all, you should ask yourself what a small giant is.
      >> The phrase "small giant" is an oxymoron.
      An oxymoron is a phrase that contradicts itself.
      >> Now think about whether or not an oxymoron can exist in reality.
      >> If you're literal enough, they can't exist.
      >> You'll have to figure out how to be literal with the parser.
      >> Just think away the small giant, and he'll disappear.
      The only thing left is an explanation of the interface.
      Read your manual to find out how to do so, and the giant should disappear.
    [hint] How do I climb down the cliff?
      >> Do you have anything like a rope in your inventory?
      >> Of course you don't.  That would be too simple of a puzzle.
      Do you see any formations on the rocks?
      >> And have you ever seen mountain climbers?
      They use spikes for their work.
      >> So you can use an icicle.
      Break off an icicle with your hands and use it on the cliff.
; Use further nesting to handle multiple solutions, if you want
; All of the details are hidden away on a new menu
    [subj] How do I get enough money to pay the guide?
      [comm] What is the difference in the two solutions?
        The first one requires you to be violent, but it gets you more points.
        The non-violent (second) solution gets you fewer points, although it
        does make for better family entertainment.
      [hint] Solution I
        >> If you read the comment above, you would realize that this is a
        violent solution.
        >> The banker is probably carrying money in his briefcase.
        >> He's also probably unarmed.
        >> Just shoot him and steal the money.
      [hint] Solution II
        >> This is a non-violent solution, but it's still not "nice."
        >> I guess you've been to the alley.
        >> Then you must have seen that bum.
        >> He's blind.
        >> Just steal the money from his hat.

; Third selection
  [subj] The Valley
    [hint] Why is the valley so empty?
      >> Do you see anything interesting to do here?
      >> Of course not!
      >> That's why the valley is so empty - it's too boring.
    [hint] I've fallen and I can't get up!
      >> Did you buy Life Savers?
      >> They wouldn't do you any good anyway, since you don't need candy.
      >> You still should have chosen a similarly-named product.
      >> Remember the Life Saver II?  Restore and buy it instead.

; Fourth selection
  [subj] Maps
    [gifa] The Mountains: Part I
      C:\MYUHS\MOUNT1.GIF
    [gifa] The Mountains: Part II
      C:\MYUHS\MOUNT2.GIF
    [gifa] The Valley: Part I
      C:\MYUHS\VALLEY.GIF


The Editor
==========

This is pretty much a standard text editor that uses standard text editing
keys.  You can leave multiple files open at the same time, and even though the
default filename is "*.91A", you can open any file of any type, either from
the menu bar or by entering the filename as a command line parameter.  Files
must be smaller than 64K.

If you are working on a UHS outline, the editor will make its best guess about
what type of data you will want to enter next.  It will assume that a "[hint]"
follows each "[subject]", a ">> " follows each "[hint]" or another ">> " and
an unformatted line follows any other kind of hunk.  The editor also
auto-indents your data as necessary, but it does not wrap your text to the
next line.

If you don't like the formatting that the editor suggests, you can override it
in several ways.  The first of these is to press CTRL-ENTER instead of ENTER
at the end of the line; when you do this, the editor does not insert any hunk
types on the next line.  A number of function keys are also provided to change
the hunk type that the compiler gives you.  Be careful using these, though,
because any text to the left of the cursor will be deleted.  You can also use
the CTRL-B key combination to quickly wipe out the line and unindent 2 spaces.
Press the F1 key for more information on what these keys are.


Running the Compiler
====================

Once you've created your outline, you need to get authorization from me to
use the compiler.  Send me an e-mail message or write to me through the post
office.  Addresses are listed at the bottom of this document.  Let me know
the game that you want to write hints for, and give me the file title
*exactly* as it will appear in your file.  I will send you a code that is
based on this title, so if you change the title, then the code will be
invalid.  If someone is already working on or has finished a file for this
game, I will let you know, so that you can select another game.  And once
you are finished, I will send you a registered copy of the DOS, TSR, and
Windows readers on a disk.

You will need to enter the information needed to compile your file from within
the editing environment.  Select "Compiler | Parameters" and enter the
appropriate filenames into the dialog box.  This program will assume that the
file is located in the current directory; if a file is not in that directory,
you will need to specify the drive and/or path name.  The input file is the
outline you are working on, the output is a completed .UHS file, and the 88a
header is a UHS 88a file that will be displayed on 88a-only UHS readers.  You
should use the STD_88a.UHS file or some other UHS 88a file that instructs
people on how to find a newer UHS reader so they can view your hints.  The
authorization code is the number that I will give you.

You only need to enter this information once per file; it is saved into a file
called UHSCMP.INI and will be loaded whenever you start the compiler.  The
UHSCMP.INI file should be in the same directory as the compiler.  You can
create or edit this file if you want to change the parameters without using
the dialog box (perhaps in a batch file).  Each line in UHSCMP.INI specifies
the information in the dialog box, in the same order as shown there.

Once you have specified the necessary information, select "Compiler | Compile"
from the menu bar to create a .UHS file.  You will then be informed on the
progress of compilation.  Any errors will also be reported as they are found.
If there are any errors detected during compilation, they will be listed again
after all portions of the file have been checked.  Otherwise, the file will be
closed, ready for testing and distribution.


Errors
======

Here is a list of all the possible errors in a file:

#1) Multiple titles were detected within the file.  You should have one
[subject] in the first column, and all other hunks should be indented within
that title hunk.  If you have to, create a new title and place your other
[subject]s inside that hunk.

#2) (this error will never be displayed)

#3) You specified a hunk that was not one of the ones listed above.  Check
your spelling on that line.

#4) You created a [credit] or [comment] that is longer than 10 lines, the
maximum for a 91a files.  You should change the hunk into a [hint] hunk,
with several (multi-line) hints, or break it into several [credit] or
[comment] hunks.  You might also want to consider shortening your text,
since you should rarely need more than the given space.

#5) You indented something other than a hunk inside another hunk.  A hunk
name should begin with a left square bracket ("[").  You may have simply
forgotten to add the bracket before the hunk type.  You cannot indent data
text, even for visual effect; the compiler believes that this is a new
non-hunk hunk.  If this is the case, start the text on the same column as
the rest of the data.  Or, move the semicolon of a comment to the first
column.

#6) A [GIFa] hunk should only have one line of data: the filename of the
external GIF file to be important.  Make sure that you start a new hunk on
the line after that oneline of data.

#7) You attempted to place another hunk inside a [comment] or [credit].
Remove it, or bring it to the left to place it on the same level as the
[comment] or [credit].

#8) The same as #7, only with a "parent" [hint] hunk.

#9) A character not in the range of ASCII codes between 32 and 127 was
detected.  Do not include accent characters for foreign languages, which may
cause this problem.  Also make sure that no word processing commands are in
your outline.

#10) Your line is over 78 characters.  If you can break it into two (if it
is part of the data set for a [comment], [credit], or [hint]), then do so.
If it is the title to a hunk, you must shorten the title.

One additional error will cause the compiler to stop: an invalid
authorization code.  The entire file will be checked, so that you can
continue to correct any errors while you are waiting for the authorization
code.  But you will not have a completed file to distribute.  If you do have
a code, check to make sure that the title you sent me matches the title in
the outline.


Distribution
============

This compiler may be used without any cost.  However, distribution is
limited to non-commercial BBS's, provided that this archive is not modified,
that no fee is charged for access to the UHS and its related files, and that
the BBS is open to the general public.  But please send me a letter letting
me know when the UHS has been uploaded.

Anyone else wishing to distribute the UHS must receive prior approval from
me.


Changes Since Version 1.00
==========================

1.50: Adds integrated editing environment and makes related changes.

1.02: Allows comments to be placed inside [hint]s and [comment]s.

1.01: Mentions America On-Line in compiler author information.


Jason Strautman
239 Redwood
San Antonio, TX  78209
CIS: [72337,2611]
AOL: JStrautman